home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgramD2.iso / Database Designers / Rational Rose 2000 / Rational Setup.EXE / common / lib / Win32 / OLE / Enum.pm < prev    next >
Text File  |  1998-11-15  |  3KB  |  112 lines
  1. # The documentation is at the __END__
  2.  
  3. package Win32::OLE::Enum;
  4. use strict;
  5. require Win32::OLE; # Make sure the XS bootstrap has been called
  6.  
  7. # pure XS methods:
  8. # - new
  9. # - DESTROY
  10. #
  11. # - Clone
  12. # - Next
  13. # - Reset
  14. # - Skip
  15.  
  16. sub All {
  17.     my $self = shift;
  18.     # C<All> can also be called as a class method like:
  19.     # my @list = Win32::OLE::Enum->All($Excel->Workbooks);
  20.     $self = $self->new(shift) unless ref $self;
  21.     return unless defined $self;
  22.  
  23.     my @result;
  24.     while (defined(my $next = $self->Next)) {
  25.         push @result, $next;
  26.     }
  27.     return @result;
  28. }
  29.  
  30. 1;
  31.  
  32. __END__
  33.  
  34. =head1 NAME
  35.  
  36. Win32::OLE::Enum - OLE Automation Collection Objects
  37.  
  38. =head1 SYNOPSIS
  39.  
  40.     my $Sheets = $Excel->Workbooks(1)->Worksheets;
  41.     my $Enum = Win32::OLE::Enum->new($Sheets);
  42.     my @Sheets = $Enum->All;
  43.  
  44.     while (defined(my $Sheet = $Enum->Next)) { ... }
  45.  
  46. =head1 DESCRIPTION
  47.  
  48. This module provides an interface to OLE collection objects from
  49. Perl. It defines an enumerator object closely mirroring the
  50. functionality of the IEnumVARIANT interface.
  51.  
  52. Please note that the Reset() method is not available in all implementations
  53. of OLE collections (like Excel 7). In that case the Enum object is good
  54. only for a single walk through of the collection.
  55.  
  56. =head2 Functions/Methods
  57.  
  58. =over 8
  59.  
  60. =item Win32::OLE::Enum->new($object)
  61.  
  62. Creates an enumerator for $object, which must be a valid OLE collection
  63. object. Note that correctly implemented collection objects must support
  64. the C<Count> and C<Item> methods, so creating an enumerator is not always
  65. necessary.
  66.  
  67. =item $Enum->All()
  68.  
  69. Returns a list of all objects in the collection. You have to call
  70. $Enum->Reset() before the enumerator can be used again. The previous
  71. position in the collection is lost.
  72.  
  73. This method can also be called as a class method:
  74.  
  75.     my @list = Win32::OLE::Enum->All($Collection);
  76.  
  77. =item $Enum->Clone()
  78.  
  79. Returns a clone of the enumerator maintaining the current position within
  80. the collection (if possible). Note that the C<Clone> method is often not
  81. implemented. Use $Enum->Clone() in an eval block to avoid dying if you
  82. are not sure that Clone is supported.
  83.  
  84. =item $Enum->Next( [$count] )
  85.  
  86. Returns the next element of the collection. In a list context the optional
  87. $count argument specifies the number of objects to be returned. In a scalar
  88. context only the last of at most $count retrieved objects is returned. The
  89. default for $count is 1.
  90.  
  91. =item $Enum->Reset()
  92.  
  93. Resets the enumeration sequence to the beginning. There is no guarantee that
  94. the exact same set of objects will be enumerated again (e.g. when enumerating
  95. files in a directory). The methods return value indicates the success of the
  96. operation. (Note that the Reset() method seems to be unimplemented in some
  97. applications like Excel 7. Use it in an eval block to avoid dying.)
  98.  
  99. =item $Enum->Skip( [$count] )
  100.  
  101. Skip the next $count elements of the enumeration. The default for $count is 1.
  102. The functions returns TRUE if at least $count elements could be skipped. It
  103. returns FALSE if not enough elements were left.
  104.  
  105. =back
  106.  
  107. =head1 AUTHORS/COPYRIGHT
  108.  
  109. This module is part of the Win32::OLE distribution.
  110.  
  111. =cut
  112.